package top.gytf.unifiedcall.common.support;

import top.gytf.unifiedcall.model.detail.UnifiedCallPackageDetail;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 统一调用API标记
 * <p>包含了API的协定信息，标注在类上将对该类下所有的方法生效（作为默认值）
 * @see top.gytf.unifiedcall.model.contract.ApiContract
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface UnifiedCallApi {
    /**
     * 是否直接返回原始响应
     * <p>数组形式仅用于增加未指定的含义，实际永远只取第一个
     * @see UnifiedCallApiContract#isCustomizedResponse()
     */
    boolean[] customizedResponse() default {};

    /**
     * 表示接口支持的最低版本
     * <p>如果类上与方法上均指定则取二者的最大值
     * <p>数组形式仅用于增加未指定的含义，实际永远只取第一个
     * @see UnifiedCallApiContract#getSince()
     * @see UnifiedCallPackageDetail#getVersion()
     */
    Version[] since() default {};

    /**
     * 表示接口支持的最高版本
     * <p>如果类上与方法上均指定则取二者的最小值
     * <p>数组形式仅用于增加未指定的含义，实际永远只取第一个
     * @see UnifiedCallApiContract#getUntil()
     * @see UnifiedCallPackageDetail#getVersion()
     */
    Version[] until() default {};

    /**
     * 表示一个版本号
     * @see top.gytf.unifiedcall.model.detail.Version
     */
    @interface Version {
        /**
         * 版本号字符串
         * <p>指定本字段则不会尝试使用下面几个字段进行解析
         * <p>数组模式只是用于表示未指定的状态，不支持指定多个值，多个值将只取第一个
         * @see top.gytf.unifiedcall.model.detail.Version#getValue()
         */
        String[] value() default {};

        /**
         * 主版本号
         * <p>数组模式只是用于表示未指定的状态，不支持指定多个值，多个值将只取第一个
         * @see top.gytf.unifiedcall.model.detail.Version#getMajor()
         */
        int[] major() default {};

        /**
         * 次版本号
         * <p>数组模式只是用于表示未指定的状态，不支持指定多个值，多个值将只取第一个
         * @see top.gytf.unifiedcall.model.detail.Version#getMinor()
         */
        int[] minor() default {};

        /**
         * 修订号
         * <p>数组模式只是用于表示未指定的状态，不支持指定多个值，多个值将只取第一个
         * @see top.gytf.unifiedcall.model.detail.Version#getPatch()
         */
        int[] patch() default {};
    }
}
